Overview of correlator-integrated messaging for JMS

Note: Correlator-integrated JMS is deprecated and will be removed in a future release.

The Java Message Service (JMS) provides a common programming model for asynchronously sending events and data across enterprise messaging systems. JMS supports two models, “publish-and-subscribe” for one-to-many message delivery and “point-to-point” for one-to-one message delivery. Apama’s correlator-integrated messaging for JMS supports both these models.

When configured to use correlator-integrated messaging for JMS, Apama applications map incoming JMS messages to Apama events and map outgoing Apama events to JMS messages.

Apama’s correlator-integrated messaging for JMS supports the following levels of reliability, built upon the reliability mechanisms provided by JMS:

  • BEST_EFFORT
  • AT_LEAST_ONCE
  • EXACTLY_ONCE
  • APP_CONTROLLED (can be set for only receivers, not for senders)

When the reliability level is set to EXACTLY_ONCE or AT_LEAST_ONCE or APP_CONTROLLED then delivery is guaranteed because messages are robustly retained by the broker until they are received and acknowledged by the Apama client. The APP_CONTROLLED reliability mode lets the application control when messages are acknowledged to the broker.

When the reliability level is set to BEST_EFFORT, message delivery is not guaranteed. For applications that do not require guaranteed message delivery, the BEST_EFFORT mode provides greater performance.

Note: If a license file cannot be found, the correlator is limited to BEST_EFFORT only messaging. See Running Apama without a license file.

In Apama Plugin for Eclipse, you can specify configuration for JMS, either in the correlator-integrated adapter for JMS editor or by editing sections of the XML and .properties configuration files directly. Note, however that the mapping configuration should always be edited by using Apama’s adapter editor.

Key concepts for correlator-integrated messaging for JMS

The key JMS concepts when implementing an Apama application with correlator-integrated messaging are connections, receivers, and senders.

JMS connections

To use JMS you must configure one or more named connections to the JMS broker. If you need to connect to multiple separate JMS broker instances (which may be using the same JMS provider/vendor or different ones) you need a connection for each; it’s also possible to add multiple connections for the same broker (for example, for rare cases where it improves performance scalability). In Apama Plugin for Eclipse, you can select from a variety of JMS providers that come with default connection configurations.

JMS receivers

A receiver is a single-threaded context for receiving messages from a single JMS queue or topic (with a single JMS Session and MessageConsumer object). A connection to a JMS broker can be configured with any number of receivers. Many, but not all, JMS providers support creating multiple receivers for a single queue (or in some cases, topic) either to scale throughput performance, or when using JMS “message selectors” to partition the messages on a destination.

JMS senders

A sender is a single-threaded context for sending messages (with a single JMS Session and MessageProducer object). A connection to a JMS broker can be configured with any number of senders. You can add any number of senders, but by default if no senders are explicitly configured, a single sender called “default” will be created implicitly. Each sender can send messages to any JMS destination (a queue or topic); the destination is specified on a per-message basis in the mapping rule set (either hardcoded by specifying a constant value per message type in the mapping rules or mapped from a destination field in the apama event). Messages sent by a single sender with the same JMS headers (“priority” for example) will usually be delivered in order by the provider (although this may not be the case if there is a failure), but the ordering of sends across senders is undefined. Multiple senders can be created for a single connection to scale throughput performance, or for sending messages with different senderReliability modes. Each sender is represented by its own correlator output channel.

Samples for using correlator-integrated messaging for JMS

Apama provides the following example applications in Apama Plugin for Eclipse that illustrate the use of correlator-integrated messaging for JMS. The examples are located in the APAMA_HOME\samples\correlator_jms directory.

  • simple-send-receive - This application demonstrates simple sending and receiving. It sends a sample event to a JMS queue or topic as a JMS TextMessage using the automatically configured default sender and receives the message using a statically-configured receiver.
  • dynamic-event-api - This application demonstrates how to use the event API to dynamically add and remove JMS senders and receivers. In addition, it shows how to monitor senders and receivers for errors and availability.
  • flow-control - This application demonstrates how to use the event API to avoid sending events faster than JMS can handle and a separate demonstration of how to avoid receiving messages from JMS faster than the EPL application can handle.